docs: add maintainer runbooks by ndycode · Pull Request #300 · ndycode/codex-multi-auth

ndycode · 2026-03-22T03:09:19Z

Summary

add three maintainer runbooks for adding auth/manager commands, adding config fields safely, and changing routing/account-selection policy safely
link the new runbooks from the docs portal
extend documentation integrity coverage to assert the runbooks exist

Validation

npm run test -- test/documentation.test.ts (fails due to pre-existing broken links to docs/releases/v1.2.0.md, unrelated to this PR)
Manual QA: confirmed the docs portal lists all three new runbooks and each file contains the intended workflow/QA sections

note: greptile review for oc-chatgpt-multi-auth. cite files like `lib/foo.ts:123`. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

adds three maintainer runbooks (auth/manager command, config field, routing policy), links them from the docs portal, creates the stub docs/releases/v1.2.0.md to fix a pre-existing broken link, and extends the documentation integrity test to assert all three runbooks are present.

runbook content is accurate, references the correct source files and test files, and includes token/credential-redaction reminders in the auth runbook
RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md compatibility check mentions EBUSY and EPERM but omits EAGAIN, which is part of the documented retry contract in AGENTS.md
the new keeps maintainer runbooks present test uses existsSync only — a truncated or empty runbook would still pass; other docs tests in this file validate section headings and this one could too
docs/releases/v1.2.0.md is a minimal anchor stub; it resolves the broken-link pre-condition the PR description calls out, though it contains no actual changelog content
no windows filesystem safety risks introduced; no concurrency surface touched; no vitest coverage gaps beyond the content-check weakness already noted

Confidence Score: 5/5

docs-only PR, safe to merge; two non-blocking P2 improvements identified but neither blocks correctness.
all changes are markdown documentation and a vitest existence check. no runtime code is modified, no token handling touched, no windows filesystem paths introduced. the two P2 comments (missing EAGAIN in one runbook line, weak test assertion) are cleanups — neither causes a test failure or runtime issue.
docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md line 35 (EAGAIN omission) and test/documentation.test.ts lines 266-279 (existence-only check).

Important Files Changed

Filename	Overview
docs/README.md	adds three runbook rows to the maintainer docs table; entries match the new files and existing portal link format.
docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md	new runbook for config field additions; Windows persistence note omits EAGAIN from the EBUSY/EPERM/EAGAIN retry contract documented in AGENTS.md.
docs/releases/v1.2.0.md	stub anchor file that resolves the pre-existing broken link in docs/README.md; minimal but intentional — fills the missing link target so the docs link-validation test passes.
test/documentation.test.ts	adds existence-only runbook guard; weaker than adjacent content-checking tests — a truncated runbook would still pass.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[maintainer wants to change codebase] --> B{what type of change?}
    B -->|new codex auth command| C[RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md]
    B -->|new config/settings field| D[RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md]
    B -->|routing/account-selection policy| E[RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md]

    C --> C1[lib/codex-manager.ts + lib/codex-manager/]
    C --> C2[docs/reference/commands.md]
    C --> C3[test/codex-manager-cli.test.ts + test/documentation.test.ts]
    C --> C4[npm run typecheck + lint + test]

    D --> D1[lib/config.ts + lib/schemas.ts]
    D --> D2[lib/dashboard-settings.ts / lib/unified-settings.ts]
    D --> D3[docs/configuration.md + CONFIG_FIELDS.md]
    D --> D4[test/config.test.ts + test/unified-settings.test.ts]
    D --> D5[Windows: EBUSY/EPERM/EAGAIN retry must remain covered]

    E --> E1[lib/rotation.ts + lib/forecast.ts]
    E --> E2[lib/request/failure-policy.ts + rate-limit-backoff.ts]
    E --> E3[test/rotation.test.ts + test/forecast.test.ts + test/failure-policy.test.ts]
    E --> E4[npm run typecheck + lint + targeted policy tests]

Prompt To Fix All With AI

This is a comment left during a code review.
Path: docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md
Line: 35

Comment:
**EAGAIN omitted from Windows persistence note**

`AGENTS.md` documents the retry contract as "EBUSY/EPERM/EAGAIN backoff (max 4 retries, exponential)". The compatibility check here only names `EBUSY` and `EPERM`, silently dropping `EAGAIN`. a maintainer following this runbook could add a new field, see the note, check only EBUSY/EPERM coverage, and ship without EAGAIN coverage — exactly the gap the note is meant to prevent.

```suggestion
- Recheck the Windows persistence notes when the field is written to disk; `EBUSY`, `EPERM`, and `EAGAIN` retry behavior must stay documented and covered.
```

How can I resolve this? If you propose a fix, please make it concise.

---

This is a comment left during a code review.
Path: test/documentation.test.ts
Line: 266-279

Comment:
**existence-only check; empty runbook would still pass**

the test asserts the three runbook files exist, but an accidentally emptied or truncated file passes the same assertion. the other content-heavy docs tests (e.g. the `documents stable overrides` and `documents public API stability` tests) validate key headings. consider asserting at minimum that each runbook contains `## Safe Workflow` and `## QA` so accidental truncation is caught:

```suggestion
	it("keeps maintainer runbooks present", () => {
		const runbooks = [
			"docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md",
			"docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md",
			"docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md",
		];

		for (const runbook of runbooks) {
			expect(
				existsSync(join(projectRoot, runbook)),
				`${runbook} should exist`,
			).toBe(true);
			const content = read(runbook);
			expect(content, `${runbook} must contain Safe Workflow section`).toContain("## Safe Workflow");
			expect(content, `${runbook} must contain QA section`).toContain("## QA");
		}
	});
```

How can I resolve this? If you propose a fix, please make it concise.

_{Last reviewed commit: "Add auth log redacti..."}

chatgpt-codex-connector · 2026-03-22T03:09:26Z

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Credits must be used to enable repository wide code reviews.

coderabbitai · 2026-03-22T03:09:27Z

📝 Walkthrough

Walkthrough

documentation pr adds three maintainer runbooks for safe workflows (adding codex auth commands, adding config fields, changing routing/account-selection policy), updates the maintainer docs index, adds a v1.2.0 release page, and adds a test that asserts the three runbook files exist (test/documentation.test.ts:1).

Changes

Cohort / File(s)	Summary
development runbooks `docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md`, `docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md`, `docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md`	added three new runbooks describing safe workflows. each lists target code locations (e.g. `lib/codex-manager.ts`), compatibility checks, and stepwise QA validation steps.
documentation index & release `docs/README.md`, `docs/releases/v1.2.0.md`	`docs/README.md` updated to include links to the three new runbooks. added `docs/releases/v1.2.0.md` recording v1.2.0 stable reference and links to related docs.
test validation `test/documentation.test.ts`	added a new test that enumerates the three runbook paths and asserts each exists using `existsSync` (see `test/documentation.test.ts:1`).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

notes (senior staff engineer tone, lowercase): flag missing regression tests for behavioral changes referenced by the runbooks. verify referenced code locations (lib/codex-manager.ts:1, lib/cli.ts:1) match actual implementation. check windows persistence notes and concurrency/ebusy handling where runbooks instruct making changes. ensure the file-existence test (test/documentation.test.ts:1) uses exact paths and will be updated if runbook names change.

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	title clearly summarizes the main change: adding three maintainer runbooks to the docs/development folder and registering them in the docs portal.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description check	✅ Passed	PR description is comprehensive and follows the template structure with summary, validation steps, and detailed notes. All required sections are present and substantive.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch docs/pr7-maintainer-runbooks-latest

✨ Simplify code

Create PR with simplified code
Commit simplified code in branch docs/pr7-maintainer-runbooks-latest

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Tip

CodeRabbit can scan for known vulnerabilities in your dependencies using OSV Scanner.

OSV Scanner will automatically detect and report security vulnerabilities in your project's dependencies. No additional configuration is required.

coderabbitai

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md`:
- Around line 9-15: Docs omission: add a note that interactive/prompt-heavy
commands also use lib/cli.ts and its prompt helpers; update the "Where to
Change" list to include lib/cli.ts and mention the specific prompt helpers
(promptAddAnotherAccount, promptLoginMode) referenced by lib/codex-manager.ts so
maintainers know to check lib/cli.ts when adding interactive commands.

In `@docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md`:
- Around line 9-18: Add lib/schemas.ts to the touchpoint list and note that new
config fields must update PluginConfigSchema (refer to PluginConfigSchema in
lib/schemas.ts) in addition to lib/config.ts; also add a line referencing the
Windows filesystem EBUSY/EPERM retry guidance from
docs/development/CONFIG_FIELDS.md so readers know to follow the documented retry
behavior for Windows edge cases when modifying persisted config.

In `@docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md`:
- Around line 9-17: The runbook omitted lib/accounts.ts from the list of
touchpoints; add lib/accounts.ts to the "Where to Change" section because
routing and account-selection logic reads/filters/scores accounts there. Update
the list alongside index.ts, lib/rotation.ts, etc., and mention that policy
changes affecting account data formats or scoring should update functions/types
in lib/accounts.ts (e.g., the account parsing/filtering and scoring helpers) so
reviewers know to check that file.

In `@test/documentation.test.ts`:
- Around line 270-284: The runbook existence assertions (the runbooks array and
the expects checking join(projectRoot, fieldInventoryPath) and join(projectRoot,
runbook)) are placed inside the wrong test scope; extract them into their own
test case named something like "has all required maintainer runbooks" instead of
leaving them inside "documents stable overrides separately from advanced and
internal overrides". Create a new test block that iterates the runbooks array
and asserts existsSync(join(projectRoot, ...)) for each entry (and the
fieldInventoryPath) and remove those assertions from the original test so each
test focuses on a single concern.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: c56c3537-3e83-4fd3-b9c7-668836311bcf

📥 Commits

Reviewing files that changed from the base of the PR and between 1be5e95 and 52f475a.

📒 Files selected for processing (6)

docs/README.md
docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md
docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md
docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md
docs/releases/v1.2.0.md
test/documentation.test.ts

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

GitHub Check: Greptile Review

🧰 Additional context used

📓 Path-based instructions (2)

test/**

⚙️ CodeRabbit configuration file

tests must stay deterministic and use vitest. demand regression cases that reproduce concurrency bugs, token refresh races, and windows filesystem behavior. reject changes that mock real secrets or skip assertions.

Files:

test/documentation.test.ts

docs/**

⚙️ CodeRabbit configuration file

keep README, SECURITY, and docs consistent with actual CLI flags and workflows. whenever behavior changes, require updated upgrade notes and mention new npm scripts.

Files:

docs/README.md
docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md
docs/releases/v1.2.0.md
docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md
docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md

🔇 Additional comments (2)

docs/releases/v1.2.0.md (1)

1-18: lgtm — release stub is consistent with package.json.

the version 1.2.0 and package name codex-multi-auth match package.json:2-3. relative links in the related section will be validated by the internal link test at test/documentation.test.ts:529-551.

docs/README.md (1)

66-68: lgtm — runbook links added to maintainer docs index.

the three new entries point to the runbook files added in this pr. test/documentation.test.ts:529-551 will validate these links resolve.

docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md

docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md

docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md

test/documentation.test.ts

coderabbitai

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md`:
- Around line 32-37: Update the "QA" section in the docs/dev runbook to add an
explicit token-safety callout before the "Run the real command or `--help` path"
step: instruct users to redact or avoid sharing any tokens/session data (API
keys, access tokens, session IDs) when capturing logs or output, and reference
the existing safety check pattern in test/documentation.test.ts (lines ~457-461)
so the wording aligns with project security guidelines; place this new callout
immediately above the real-command inspection bullet and ensure it clearly tells
QA to sanitize outputs before sharing.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 6dc4e48c-20ce-4339-abff-19723ce6c067

📥 Commits

Reviewing files that changed from the base of the PR and between 52f475a and 18b6911.

📒 Files selected for processing (4)

docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md
docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md
docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md
test/documentation.test.ts

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

GitHub Check: Greptile Review

🧰 Additional context used

📓 Path-based instructions (2)

test/**

⚙️ CodeRabbit configuration file

tests must stay deterministic and use vitest. demand regression cases that reproduce concurrency bugs, token refresh races, and windows filesystem behavior. reject changes that mock real secrets or skip assertions.

Files:

test/documentation.test.ts

docs/**

⚙️ CodeRabbit configuration file

keep README, SECURITY, and docs consistent with actual CLI flags and workflows. whenever behavior changes, require updated upgrade notes and mention new npm scripts.

Files:

docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md
docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md
docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md

🔇 Additional comments (3)

test/documentation.test.ts (1)

266-279: good extraction into a dedicated runbook-presence test.

line 266 keeps this concern isolated and deterministic, and it aligns with the surrounding docs integrity suite in test/documentation.test.ts:104-556.

docs/development/RUNBOOK_ADD_CONFIG_FIELD_SAFELY.md (1)

11-41: looks solid. schemas + windows persistence guidance are now explicit.

the touchpoints and compatibility checks are clear, and line 34 now anchors the ebusy/eperm expectation that aligns with docs integrity coverage in test/documentation.test.ts:296-301.

docs/development/RUNBOOK_CHANGE_ROUTING_POLICY_SAFELY.md (1)

11-38: good coverage of routing-policy touchpoints and validation flow.

including lib/accounts.ts on line 12 and the focused policy test set on line 18 makes this runbook actionable and consistent with related checks in test/documentation.test.ts:383-420.

docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md

docs: add maintainer runbooks

75424bc

docs: add v1.2.0 release notes stub

52f475a

coderabbitai bot requested changes Mar 22, 2026

View reviewed changes

docs: tighten maintainer runbooks

18b6911

coderabbitai bot requested changes Mar 22, 2026

View reviewed changes

docs/development/RUNBOOK_ADD_AUTH_MANAGER_COMMAND.md Show resolved Hide resolved

Add auth log redaction QA note

dd90b77

coderabbitai bot approved these changes Mar 22, 2026

View reviewed changes

ndycode mentioned this pull request Mar 22, 2026

release: merge current main-target PR set #318

Merged

ndycode merged commit dafb9bd into main Mar 23, 2026
2 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: add maintainer runbooks#300

docs: add maintainer runbooks#300
ndycode merged 4 commits intomainfrom
docs/pr7-maintainer-runbooks-latest

ndycode commented Mar 22, 2026 •

edited by greptile-apps bot

Loading

Uh oh!

chatgpt-codex-connector bot commented Mar 22, 2026

Uh oh!

coderabbitai bot commented Mar 22, 2026 •

edited

Loading

Walkthrough

Changes

Estimated code review effort

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

ndycode commented Mar 22, 2026 • edited by greptile-apps bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Validation

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Flowchart

Uh oh!

chatgpt-codex-connector bot commented Mar 22, 2026

Uh oh!

coderabbitai bot commented Mar 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Estimated code review effort

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

coderabbitai bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

ndycode commented Mar 22, 2026 •

edited by greptile-apps bot

Loading

note: greptile review for oc-chatgpt-multi-auth. cite files like `lib/foo.ts:123`. confirm regression tests + windows concurrency/token redaction coverage.

coderabbitai bot commented Mar 22, 2026 •

edited

Loading